<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Arduino LibHelix: A MP3 and AAC Decoder using Helix</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Arduino LibHelix
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">A MP3 and AAC Decoder using Helix </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md_README"></a> I am providing the <a href="https://en.wikipedia.org/wiki/Helix_Universal_Server">Helix MP3 decoder from RealNetworks</a> as a simple Arduino Library. The Helix decoders are based on 16bits integers, so they are a perfect fit to be used in Microcontrollers.</p>
<p>MP3 is a compressed audio file formats based on PCM. A 2.6 MB wav file can be compressed down to 476 kB MP3.</p>
<p>This project can be used stand alone or together with the <a href="https://github.com/pschatzmann/arduino-audio-tools">arduino-audio_tools library</a>. It can also be used from non Arduino based systems with the help of cmake.</p>
<p>The Helix MP3 decoder provides Layer 3 support for MPEG-1, MPEG-2, and MPEG-2.5. It supports variable bit rates, constant bit rates, and stereo and mono audio formats.</p>
<h1><a class="anchor" id="autotoc_md1"></a>
API Example</h1>
<p>The API provides the decoded data to a <b>Arduino Stream</b> or alternatively to a callback function. The platform dependent I2S implementations usually implement I2S as subclass of Stream, so you can just provide the corresponding I2S object to the constructor.</p>
<p>Here is a MP3 example using the callback:</p>
<div class="fragment"><div class="line">#include &quot;MP3DecoderHelix.h&quot;</div>
<div class="line">#include &quot;music_mp3.h&quot;</div>
<div class="line"> </div>
<div class="line">using namespace libhelix;</div>
<div class="line"> </div>
<div class="line">void dataCallback(MP3FrameInfo &amp;info, int16_t *pcm_buffer, size_t len, void*) {</div>
<div class="line">    for (int i=0; i&lt;len; i+=info.nChans){</div>
<div class="line">        for (int j=0;j&lt;info.nChans;j++){</div>
<div class="line">            Serial.print(pcm_buffer[i+j]);</div>
<div class="line">            Serial.print(&quot; &quot;);</div>
<div class="line">        }</div>
<div class="line">        Serial.println();</div>
<div class="line">    }</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">MP3DecoderHelix mp3(dataCallback);</div>
<div class="line"> </div>
<div class="line">void setup() {</div>
<div class="line">    Serial.begin(115200);</div>
<div class="line">    mp3.begin();</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">void loop() {</div>
<div class="line">    Serial.println(&quot;writing...&quot;);</div>
<div class="line">    mp3.write(music_data, music_len);    </div>
<div class="line"> </div>
<div class="line">    // restart from the beginning</div>
<div class="line">    delay(2000);</div>
<div class="line">    mp3.begin();</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md2"></a>
Installation</h1>
<p>For Arduino, you can download the library as zip and call include Library -&gt; zip library. Or you can git clone this project into the Arduino libraries folder e.g. with</p>
<div class="fragment"><div class="line">cd  ~/Documents/Arduino/libraries</div>
<div class="line">git clone pschatzmann/arduino-libhelix.git</div>
</div><!-- fragment --><p>This project can also be built and executed on your desktop with cmake:</p>
<div class="fragment"><div class="line">cd arduino-libhelix</div>
<div class="line">mkdir build</div>
<div class="line">cd build</div>
<div class="line">cmake ..</div>
<div class="line">make</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md3"></a>
Parameters</h1>
<p>The decoder needs to allocate a buffer to store a frame and the decoded data. The following default values have been defined in <a class="el" href="_config_helix_8h_source.html">ConfigHelix.h</a>:</p>
<div class="fragment"><div class="line">#define MP3_MAX_OUTPUT_SIZE 1024 * 5</div>
<div class="line">#define MP3_MAX_FRAME_SIZE 1024 * 2 </div>
<div class="line">#define AAC_MAX_OUTPUT_SIZE 1024 * 8 </div>
<div class="line">#define AAC_MAX_FRAME_SIZE 2100 </div>
</div><!-- fragment --><p>These values are working with standard bitrates, but in some exceptional cases (with extreme (220kbs) or insane (320kbs) bitrates) you might need to increase these values e.g. to </p><div class="fragment"><div class="line">#define MP3_MAX_OUTPUT_SIZE 1024 * 10</div>
<div class="line">#define MP3_MAX_FRAME_SIZE 3200</div>
</div><!-- fragment --><p>Alternatively you can set the values in your sketch by calling the following methods: </p><div class="fragment"><div class="line">setMaxPCMSize(int size)</div>
<div class="line">setMaxFrameSize(int size)</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md4"></a>
Memory Management</h1>
<p>On the ESP32 we support PSRAM: just activate it in the Arduino Tools menu and all the memory will be allocated in PSRAM.</p>
<h1><a class="anchor" id="autotoc_md5"></a>
Logging</h1>
<p>You can define the log level as Debug, Info, Warning, Error </p><div class="fragment"><div class="line">LOGLEVEL_HELIX = LogLevelHelix::Info;</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md6"></a>
Documentation</h1>
<ul>
<li>The <a href="https://pschatzmann.github.io/arduino-libhelix/html/annotated.html">Class Documentation can be found here</a></li>
<li>I also suggest that you have a look at <a href="https://www.pschatzmann.ch/home/tag/codecs/">my related blogs</a></li>
</ul>
<p>I recommend to use this library together with my <a href="https://github.com/pschatzmann/arduino-audio-tools">Arduino Audio Tools</a>. This is just one of many codecs that I have collected so far: Further details can be found in the <a href="https://github.com/pschatzmann/arduino-audio-tools/wiki/Encoding-and-Decoding-of-Audio">Encoding and Decoding Wiki</a> of the Audio Tools.</p>
<h2><a class="anchor" id="autotoc_md7"></a>
Final Comments</h2>
<p>This library is based on a adapted version of libhelix from <a href="https://github.com/earlephilhower/ESP8266Audio">Earle Phil Hower's ESP8288Audio library</a> <br  />
 The decoder code is from the Helix project and licensed under RealNetwork's <a href="https://github.com/pschatzmann/arduino-libhelix/blob/main/src/libhelix-mp3/RPSL.txt">RPSL license</a>. For commercial use you might still going to need the usual AAC licensing. </p>
</div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>
